<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Building The Documentation</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Documentation"
HREF="docguide.html"><LINK
REL="PREVIOUS"
TITLE="Tool Sets"
HREF="docguide-toolsets.html"><LINK
REL="NEXT"
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Tool Sets"
HREF="docguide-toolsets.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Appendix I. Documentation</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Documentation Authoring"
HREF="docguide-authoring.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DOCGUIDE-BUILD"
>I.3. Building The Documentation</A
></H1
><P
>   Once you have everything set up, change to the directory
   <TT
CLASS="FILENAME"
>doc/src/sgml</TT
> and run one of the commands
   described in the following subsections to build the
   documentation. (Remember to use GNU make.)
  </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138286"
>I.3.1. HTML</A
></H2
><P
>    To build the <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> version of the documentation:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake html</KBD
></PRE
><P>
    This is also the default target.  The output appears in the
    subdirectory <TT
CLASS="FILENAME"
>html</TT
>.
   </P
><P
>    To create a proper index, the build might process several identical
    stages.  If you do not care about the index, and just want to
    proof-read the output, use <TT
CLASS="LITERAL"
>draft</TT
>:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake draft</KBD
></PRE
><P>
   </P
><P
>    To build the documentation as a single HTML page, use:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.html</KBD
></PRE
><P>
   </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138303"
>I.3.2. Manpages</A
></H2
><P
>   We use the DocBook XSL stylesheets to
   convert <SPAN
CLASS="PRODUCTNAME"
>DocBook</SPAN
>
   <CODE
CLASS="SGMLTAG"
>refentry</CODE
> pages to *roff output suitable for man
   pages.  The man pages are also distributed as a tar archive,
   similar to the <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> version.  To create the man
   pages, use the commands:
</P><PRE
CLASS="PROGRAMLISTING"
>cd doc/src/sgml
gmake man</PRE
><P>
  </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138310"
>I.3.3. Print Output via <SPAN
CLASS="APPLICATION"
>JadeTeX</SPAN
></A
></H2
><P
>    If you want to use <SPAN
CLASS="APPLICATION"
>JadeTex</SPAN
> to produce a
    printable rendition of the documentation, you can use one of the
    following commands:

    <P
></P
></P><UL
><LI
><P
>       To generate PostScript via <ACRONYM
CLASS="ACRONYM"
>DVI</ACRONYM
> in A4 format:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres-A4.ps</KBD
></PRE
><P>
       In U.S. letter format:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres-US.ps</KBD
></PRE
><P>
      </P
></LI
><LI
><P
>       To make a <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres-A4.pdf</KBD
></PRE
><P>
       or:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres-US.pdf</KBD
></PRE
><P>
       (Of course you can also make a <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
> version
       from the PostScript, but if you generate <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>
       directly, it will have hyperlinks and other enhanced features.)
      </P
></LI
></UL
><P>
   </P
><P
>    When using JadeTeX to build the PostgreSQL documentation, you will
    probably need to increase some of TeX's internal parameters.  These
    can be set in the file <TT
CLASS="FILENAME"
>texmf.cnf</TT
>.  The following
    settings worked at the time of this writing:
</P><PRE
CLASS="PROGRAMLISTING"
>hash_extra.jadetex  = 200000
hash_extra.pdfjadetex  = 200000
pool_size.jadetex = 2000000
pool_size.pdfjadetex = 2000000
string_vacancies.jadetex = 150000
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
save_size.jadetex = 15000
save_size.pdfjadetex = 15000</PRE
><P>
   </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138339"
>I.3.4. Overflow Text</A
></H2
><P
>    Occasionally text is too wide for the printed margins, and in
    extreme cases, too wide for the printed page, e.g.  non-wrapped
    text, wide tables.  Overly wide text generates <SPAN
CLASS="QUOTE"
>"Overfull
    hbox"</SPAN
> messages in the TeX log output file, e.g.
    <TT
CLASS="FILENAME"
>postgres-US.log</TT
> or <TT
CLASS="FILENAME"
>postgres-A4.log</TT
>.
    There are 72 points in an inch so anything reported as over 72
    points too wide will probably not fit on the printed page (assuming
    one inch margins).  To find the <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
> text
    causing the overflow, find the first page number mentioned above
    the overflow message, e.g.  <TT
CLASS="LITERAL"
>[50 ###]</TT
> (page 50), and
    look at the page after that (e.g. page 51) in the <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>
    file to see the overflow text and adjust the <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
>
    accordingly.
   </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138349"
>I.3.5. Print Output via <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
></A
></H2
><P
>    You can also create a printable version of the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
    documentation by converting it to <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> and
    applying minor formatting corrections using an office suite.
    Depending on the capabilities of the particular office suite, you
    can then convert the documentation to PostScript of
    <ACRONYM
CLASS="ACRONYM"
>PDF</ACRONYM
>.  The procedure below illustrates this
    process using <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>.
   </P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>     It appears that current versions of the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> documentation
     trigger some bug in or exceed the size limit of OpenJade.  If the
     build process of the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> version hangs for a
     long time and the output file still has size 0, then you might have
     hit that problem.  (But keep in mind that a normal build takes 5
     to 10 minutes, so don't abort too soon.)
    </P
></BLOCKQUOTE
></DIV
><DIV
CLASS="PROCEDURE"
><P
><B
><SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> Cleanup</B
></P
><P
>     <SPAN
CLASS="APPLICATION"
>OpenJade</SPAN
> omits specifying a default
     style for body text. In the past, this undiagnosed problem led to
     a long process of table of contents generation. However, with
     great help from the <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> folks
     the symptom was diagnosed and a workaround is available.
    </P
><OL
TYPE="1"
><LI
CLASS="STEP"
><P
>      Generate the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> version by typing:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake postgres.rtf</KBD
></PRE
><P>
     </P
></LI
><LI
CLASS="STEP"
><P
>      Repair the RTF file to correctly specify all styles, in
      particular the default style. If the document contains
      <CODE
CLASS="SGMLTAG"
>refentry</CODE
> sections, one must also replace
      formatting hints which tie a preceding paragraph to the current
      paragraph, and instead tie the current paragraph to the
      following one. A utility, <TT
CLASS="COMMAND"
>fixrtf</TT
>, is
      available in <TT
CLASS="FILENAME"
>doc/src/sgml</TT
> to accomplish
      these repairs:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>./fixrtf --refentry postgres.rtf</KBD
></PRE
><P>
     </P
><P
>      The script adds <TT
CLASS="LITERAL"
>{\s0 Normal;}</TT
> as the zeroth
      style in the document. According to
      <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>, the RTF standard would
      prohibit adding an implicit zeroth style, though Microsoft Word
      happens to handle this case. For repairing
      <CODE
CLASS="SGMLTAG"
>refentry</CODE
> sections, the script replaces
      <TT
CLASS="LITERAL"
>\keepn</TT
> tags with <TT
CLASS="LITERAL"
>\keep</TT
>.
     </P
></LI
><LI
CLASS="STEP"
><P
>      Open a new document in <SPAN
CLASS="PRODUCTNAME"
>Applixware Words</SPAN
> and
      then import the <ACRONYM
CLASS="ACRONYM"
>RTF</ACRONYM
> file.
     </P
></LI
><LI
CLASS="STEP"
><P
>      Generate a new table of contents (ToC) using
      <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
>.
     </P
><OL
CLASS="SUBSTEPS"
TYPE="a"
><LI
CLASS="STEP"
><P
>        Select the existing ToC lines, from the beginning of the first
        character on the first line to the last character of the last
        line.
       </P
></LI
><LI
CLASS="STEP"
><P
>        Build a new ToC using
        <SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-&gt;<SPAN
CLASS="GUISUBMENU"
>Book
        Building</SPAN
>-&gt;<SPAN
CLASS="GUIMENUITEM"
>Create Table of
        Contents</SPAN
>. Select the first three
        levels of headers for inclusion in the ToC. This will replace
        the existing lines imported in the RTF with a native
        <SPAN
CLASS="PRODUCTNAME"
>Applixware</SPAN
> ToC.
       </P
></LI
><LI
CLASS="STEP"
><P
>        Adjust the ToC formatting by using
        <SPAN
CLASS="GUIMENU"
>Format</SPAN
>-&gt;<SPAN
CLASS="GUIMENUITEM"
>Style</SPAN
>,
        selecting each of the three ToC styles, and adjusting the
        indents for <TT
CLASS="LITERAL"
>First</TT
> and
        <TT
CLASS="LITERAL"
>Left</TT
>. Use the following values:

        <DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN138412"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Style</TH
><TH
>First Indent (inches)</TH
><TH
>Left Indent (inches)</TH
></TR
></THEAD
><TBODY
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 1</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.4</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.4</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 2</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.8</TT
></TD
><TD
><TT
CLASS="LITERAL"
>0.8</TT
></TD
></TR
><TR
><TD
><TT
CLASS="LITERAL"
>TOC-Heading 3</TT
></TD
><TD
><TT
CLASS="LITERAL"
>1.2</TT
></TD
><TD
><TT
CLASS="LITERAL"
>1.2</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
       </P
></LI
></OL
></LI
><LI
CLASS="STEP"
><P
>      Work through the document to:

      <P
></P
></P><UL
><LI
><P
>         Adjust page breaks.
        </P
></LI
><LI
><P
>         Adjust table column widths.
        </P
></LI
></UL
><P>
     </P
></LI
><LI
CLASS="STEP"
><P
>      Replace the right-justified page numbers in the Examples and
      Figures portions of the ToC with correct values. This only takes
      a few minutes.
     </P
></LI
><LI
CLASS="STEP"
><P
>       Delete the index section from the document if it is empty.
     </P
></LI
><LI
CLASS="STEP"
><P
>       Regenerate and adjust the table of contents.
     </P
><OL
CLASS="SUBSTEPS"
TYPE="a"
><LI
CLASS="STEP"
><P
>         Select the ToC field.
        </P
></LI
><LI
CLASS="STEP"
><P
>         Select <SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-&gt;<SPAN
CLASS="GUISUBMENU"
>Book
         Building</SPAN
>-&gt;<SPAN
CLASS="GUIMENUITEM"
>Create Table of
         Contents</SPAN
>.
        </P
></LI
><LI
CLASS="STEP"
><P
>         Unbind the ToC by selecting
         <SPAN
CLASS="GUIMENU"
>Tools</SPAN
>-&gt;<SPAN
CLASS="GUISUBMENU"
>Field
         Editing</SPAN
>-&gt;<SPAN
CLASS="GUIMENUITEM"
>Unprotect</SPAN
>.
        </P
></LI
><LI
CLASS="STEP"
><P
>         Delete the first line in the ToC, which is an entry for the
         ToC itself.
        </P
></LI
></OL
></LI
><LI
CLASS="STEP"
><P
>      Save the document as native <SPAN
CLASS="PRODUCTNAME"
>Applixware
      Words</SPAN
> format to allow easier last minute editing
      later.
     </P
></LI
><LI
CLASS="STEP"
><P
>      <SPAN
CLASS="QUOTE"
>"Print"</SPAN
> the document
      to a file in PostScript format.
     </P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138477"
>I.3.6. Plain Text Files</A
></H2
><P
>    Several files are distributed as plain text, for reading during
    the installation process. The <TT
CLASS="FILENAME"
>INSTALL</TT
> file
    corresponds to <A
HREF="installation.html"
>Chapter 15</A
>, with some minor
    changes to account for the different context.  To recreate the
    file, change to the directory <TT
CLASS="FILENAME"
>doc/src/sgml</TT
>
    and enter <KBD
CLASS="USERINPUT"
>gmake INSTALL</KBD
>.  This will create
    a file <TT
CLASS="FILENAME"
>INSTALL.html</TT
> that can be saved as text
    with <SPAN
CLASS="PRODUCTNAME"
>Netscape Navigator</SPAN
> and put into
    the place of the existing file.
    <SPAN
CLASS="PRODUCTNAME"
>Netscape</SPAN
> seems to offer the best
    quality for <ACRONYM
CLASS="ACRONYM"
>HTML</ACRONYM
> to text conversions (over
    <SPAN
CLASS="APPLICATION"
>lynx</SPAN
> and
    <SPAN
CLASS="APPLICATION"
>w3m</SPAN
>).
   </P
><P
>    The file <TT
CLASS="FILENAME"
>HISTORY</TT
> can be created similarly,
    using the command <KBD
CLASS="USERINPUT"
>gmake HISTORY</KBD
>.  For the
    file <TT
CLASS="FILENAME"
>src/test/regress/README</TT
> the command is
    <KBD
CLASS="USERINPUT"
>gmake regress_README</KBD
>.
   </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN138495"
>I.3.7. Syntax Check</A
></H2
><P
>    Building the documentation can take very long.  But there is a
    method to just check the correct syntax of the documentation
    files, which only takes a few seconds:
</P><PRE
CLASS="SCREEN"
><SAMP
CLASS="PROMPT"
>doc/src/sgml$ </SAMP
><KBD
CLASS="USERINPUT"
>gmake check</KBD
></PRE
><P>
   </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docguide-toolsets.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="docguide-authoring.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Tool Sets</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docguide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Documentation Authoring</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>